feat(nix): install packaged shell completions - #947

Status

Implementation LGTM after independent review. The Nix packaging policy is approved: bundle completion files, let the shell control activation, and leave user startup files untouched. All required CI checks and Security passed for implementation commit 3cd948038df2157c2cb09fe2980345666f471f39; the follow-up only clarifies documentation. Not merged.

Motivation

Nix users should receive completion files with the package, without running a separate installer or modifying shell startup files. Keeping the files in the package also keeps them aligned with the installed CLI version.

What it does

• Installs Bash, Fish, and Zsh completions through Nixpkgs' installShellFiles hook.
• Generates files only when the build platform can execute the host platform.
• Runs generation sequentially so a nonzero exit fails the build, including after partial output.
• Checks in CI that all three packaged files match fresh CLI output.
• Documents activation, installer ownership, and tip behavior for Nix completions.

Proof it works

• GitHub CI: Linux, macOS, and Windows tests, lint/type checking, Nix build and packaged-completion verification, and the required aggregate check all pass.
• GitHub Security: dependency review, audits, and website lockfile validation pass.
• Real Nix build on aarch64-linux; packaged CLI reports 1.11.0.
• All three installed files are nonempty, byte-identical to fresh output, and pass their shell's syntax check.
• nix flake check --no-build --all-systems evaluates all four supported systems.
• Exact-hook failure injection with Nixpkgs' installer: a generator that prints partial output then exits 17 is incorrectly accepted by the original hook (exit 0); the hardened hook exits 17 before installation.
• Type checking, lint, and 333 focused completion tests pass.
• Full suite in an isolated Linux environment with Node.js 22.21.1: 4,229 tests pass across 145 files.

Notes

• Approved policy: Nix packages include completion files as a documented exception to explicit CLI installation. Shell configuration controls activation and may load them automatically. OpenSpec does not modify startup files when installing the Nix package.
• The CLI reference now distinguishes package-managed completions from user-local copies. CLI install/uninstall and installed-file detection manage the latter, not the immutable Nix package. The installation guide links to that explanation. OPENSPEC_NO_COMPLETIONS=1 suppresses the tip; it does not disable active completions. No core-code expansion is proposed to manage the Nix store.
• Reconciled the branch with current main; retained its Node.js and dependency versions. No application code or dependency changes.
• Does not edit .bashrc, .zshrc, or Fish configuration. Users still need their shell's completion subsystem enabled.
• Telemetry is disabled only during generation and verification, not in the installed CLI.
• Host-wide tests exposed existing environment leaks through Oh My Zsh and global MiniMax skills. Those user settings were left untouched; all affected cases pass in the clean Linux full-suite run.